negotiator.utility
Class UtilitySpace

java.lang.Object
  negotiator.utility.UtilitySpace

public class UtilitySpace
extends java.lang.Object

Wouter: the utility space couples all objectives to weights and evaluators. A utilityspace currently is not bound to one agent. I can see some security issues with that... Wouter: this class is final to prevent users (students) to override the getUtility function with their own version of UtilitySpace Wouter 15nov: un-done the final, students may hack what they want, but they work with a copy anyway.

Author:

D. Tykhonov, K. Hindriks, W. Pasman

Constructor Summary

UtilitySpace()
Creates an empty utility space.

UtilitySpace(Domain domain)
Creates a new utilityspace of the given domain.

UtilitySpace(Domain domain, java.lang.String fileName)
Create new default util space for a given domain.

UtilitySpace(UtilitySpace us)
Copies the data from another UtilitySpace.

Method Summary

Evaluator	addEvaluator(Objective obj) Adds an evaluator to an objective or issue
Evaluator	addEvaluator(Objective obj, Evaluator ev) Sets an pair.
void	checkReadyForNegotiation(Domain dom) check if this utility space is ready for negotiation.
Evaluator	DefaultEvaluator(Objective obj) create a default evaluator for a given Objective.
static double	discount(double util, double time, double discountFactor) Computes: discountedUtil = util * Math.pow(discount, time).
boolean	equals(java.lang.Object obj)
double	getDiscountFactor()
Domain	getDomain()
double	getEvaluation(int pIssueIndex, Bid bid) Returns the utility of one issue in the bid.
Evaluator	getEvaluator(int index)
java.util.Set<java.util.Map.Entry<Objective,Evaluator>>	getEvaluators()
java.lang.String	getFileName()
Objective	getIssue(int index) Deprecated. Use getObjective
Bid	getMaxUtilityBid() Totally revised, brute-force search now.
Bid	getMinUtilityBid() Returns the the worst bid.
int	getNrOfEvaluators()
Objective	getObjective(int index) Returns the Objective or Issue at that index
java.lang.Double	getReservationValue() The reservation value is the least favourable point at which one will accept a negotiated agreement.
double	getReservationValueUndiscounted() Equivalent to getReservationValue(), but always returns a double value.
double	getReservationValueWithDiscount(double time) The discounted version of getReservationValue().
double	getReservationValueWithDiscount(Timeline timeline) The discounted version of getReservationValue().
double	getUtility(Bid bid)
double	getUtilityWithDiscount(Bid bid, double time)
double	getUtilityWithDiscount(Bid bid, long timeAfterStart, long deadline) Deprecated.
double	getUtilityWithDiscount(Bid bid, Timeline timeline) Let d in (0, 1) be the discount factor.
double	getWeight(int issueID)
negotiator.xml.SimpleElement	getXMLRoot()
java.lang.String	IsComplete() Wouter: this function *should* check that the domainSubtreeP is a subtree of the utilSubtreeP, and that all leaf nodes are complete.
boolean	lock(Objective obj) Place a lock on the weight of an objective or issue.
java.util.Set<java.util.Map.Entry<Objective,Evaluator>>	normalizeChildren(Objective obj) Normalizes the weights of objectives of the given objective so that they sum up to one.
boolean	removeEvaluator(Objective obj) Removes an evaluator.
void	setDiscount(double newDiscount)
void	setReservationValue(double newRV)
double	setWeight(Objective objective, double weight) Method used to set the weight of the given objective.
void	setWeightSimple(Objective objective, double weight) Method which sets the weight of an issue without checking normalization.
negotiator.xml.SimpleElement	toXML() Creates an xml representation (in the form of a SimpleElements) of the utilityspace.
boolean	unlock(Objective obj) Clear a lock on the weight of an objective or issue.

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UtilitySpace

public UtilitySpace()

Creates an empty utility space.

UtilitySpace

public UtilitySpace(Domain domain)

Creates a new utilityspace of the given domain.

Parameters:

domain - for which the utilityspace should be specified.

UtilitySpace

public UtilitySpace(Domain domain,
                    java.lang.String fileName)
             throws java.lang.Exception

Create new default util space for a given domain.

Parameters:

domain -

fileName - to read domain from. Set fileName to "" if no file available, in which case default evaluators are loaded..

Throws:

java.lang.Exception - if error occurs, e.g. if domain does not match the util space, or file not found.

UtilitySpace

public UtilitySpace(UtilitySpace us)

Copies the data from another UtilitySpace.

Parameters:

us - utilityspace to be cloned.

Method Detail

DefaultEvaluator

public Evaluator DefaultEvaluator(Objective obj)

create a default evaluator for a given Objective. This function is placed here, and not in Objective, because the Objectives should not be loaded with utility space functionality. The price we pay for that is that we now have an ugly switch inside the code, losing some modularity.

Parameters:

obj - the objective to create an evaluator for

Returns:

the default evaluator

checkReadyForNegotiation

public void checkReadyForNegotiation(Domain dom)
                              throws java.lang.Exception

check if this utility space is ready for negotiation.

Parameters:

dom - is the domain in which nego is taking place

Throws:

java.lang.Exception - if utility space is incomplete (@see isComplete());

getXMLRoot

public negotiator.xml.SimpleElement getXMLRoot()

Returns:

XML root of this utilityspace.

getNrOfEvaluators

public final int getNrOfEvaluators()

Returns:

number of issues.

getEvaluator

public final Evaluator getEvaluator(int index)

Parameters:

index - The IDnumber of the Objective or Issue

Returns:

An Evaluator for the Objective or Issue.

getUtility

public double getUtility(Bid bid)
                  throws java.lang.Exception

Parameters:

bid - of which we are interested in its utility.

Returns:

undiscounted utility of the given bid.

Throws:

java.lang.Exception - when bid is incomplete or invalid.

getUtilityWithDiscount

@Deprecated
public double getUtilityWithDiscount(Bid bid,
                                                long timeAfterStart,
                                                long deadline)
                              throws java.lang.Exception

Deprecated.

Deprecated: uses old timing protocol.

Parameters:

bid -

timeAfterStart -

deadline -

Returns:

discounted utility.

Throws:

java.lang.Exception

getUtilityWithDiscount

public double getUtilityWithDiscount(Bid bid,
                                     Timeline timeline)

Let d in (0, 1) be the discount factor. (If d <= 0 or d >= 1, we assume that d = 1.) Let t in [0, 1] be the current time, as defined by the Timeline. We compute the discounted utility discountedUtility as follows: discountedUtility = originalUtility * d^t. For t = 0 the utility remains unchanged, and for t = 1 the original utility is multiplied by the discount factor. The effect is almost linear in between.

Parameters:

bid - of which we are interested in its utility.

timeline - indicating the time passed in the negotiation.

Returns:

discounted utility.

getUtilityWithDiscount

public double getUtilityWithDiscount(Bid bid,
                                     double time)

Parameters:

bid - of which we want to know the utility at the given time.

time - at which we want to know the utility of the bid.

Returns:

discounted utility.

See Also:

getUtilityWithDiscount(Bid, Timeline)

discount

public static double discount(double util,
                              double time,
                              double discountFactor)

Computes: discountedUtil = util * Math.pow(discount, time). Checks for bounds on the discount factor and time.

Parameters:

util - undiscounted utility.

time - at which we want to know the discounted utility.

discountFactor - of the preference profile.

Returns:

discounted version of the given utility at the given time.

getEvaluation

public final double getEvaluation(int pIssueIndex,
                                  Bid bid)
                           throws java.lang.Exception

Returns the utility of one issue in the bid. Note that this value is in the range [0,1] as it is not normalized by the issue weight.

Parameters:

pIssueIndex - of the issue.

bid -

Returns:

evaluation of the value of the issue of the given bid.

Throws:

java.lang.Exception - if the bid or value is null.

getMaxUtilityBid

public final Bid getMaxUtilityBid()
                           throws java.lang.Exception

Totally revised, brute-force search now.

Returns:

a bid with the maximum utility value attainable in this util space

Throws:

java.lang.Exception - if there is no bid at all in this util space.

getMinUtilityBid

public Bid getMinUtilityBid()
                     throws java.lang.Exception

Returns the the worst bid.

Returns:

a bid with the lowest possible utility

Throws:

java.lang.Exception - if there is no bid at all in the util space

getWeight

public double getWeight(int issueID)

Parameters:

issueID - The Issue or Objective to get the weight from

Returns:

The weight, or -1 if the objective doesn't exist.

setWeightSimple

public void setWeightSimple(Objective objective,
                            double weight)

Method which sets the weight of an issue without checking normalization. This is faster than setWeightSimple if normalization is ensured.

Parameters:

objective - of which the weights must be set.

weight - to which the weight of the objective must be set.

setWeight

public double setWeight(Objective objective,
                        double weight)

Method used to set the weight of the given objective.

Parameters:

objective - of which the weights must be set.

weight - to which the weight of the objective must be set.

Returns:

the new weight of the issue after normalization.

getIssue

public final Objective getIssue(int index)

Deprecated. Use getObjective

Parameters:

index - The index of the issue to

Returns:

the indexed objective or issue

getObjective

public final Objective getObjective(int index)

Returns the Objective or Issue at that index

Parameters:

index - The index of the Objective or Issue.

Returns:

An Objective or Issue.

getDomain

public final Domain getDomain()

Returns:

domain belonging to this preference profile.

addEvaluator

public final Evaluator addEvaluator(Objective obj)

Adds an evaluator to an objective or issue

Parameters:

obj - The Objective or Issue to attach an Evaluator to.

Returns:

The new Evaluator.

addEvaluator

public final Evaluator addEvaluator(Objective obj,
                                    Evaluator ev)

Sets an pair. Replaces old evaluator for objective

Parameters:

obj - The Objective to attach an Evaluator to.

ev - The Evaluator to attach.

Returns:

the given evaluator Wouter: what's the use of the return value???

getEvaluators

public final java.util.Set<java.util.Map.Entry<Objective,Evaluator>> getEvaluators()

Returns:

The set with all pairs of evaluators and objectives in this utilityspace.

lock

public final boolean lock(Objective obj)

Place a lock on the weight of an objective or issue.

Parameters:

obj - The objective or issue that is about to have it's weight locked.

Returns:

true if succesfull, false If the objective doesn't have an evaluator yet.

unlock

public final boolean unlock(Objective obj)

Clear a lock on the weight of an objective or issue.

Parameters:

obj - The objective or issue that is having it's lock cleared.

Returns:

true If the lock is cleared, false if the objective or issue doesn't have an evaluator yet.

normalizeChildren

public final java.util.Set<java.util.Map.Entry<Objective,Evaluator>> normalizeChildren(Objective obj)

Normalizes the weights of objectives of the given objective so that they sum up to one.

Parameters:

obj - of which the weights must be normalized.

Returns:

all evaluators using getEvaluators().

removeEvaluator

public boolean removeEvaluator(Objective obj)

Removes an evaluator.

Parameters:

obj - to be removed.

Returns:

true is successfully removed.

toXML

public negotiator.xml.SimpleElement toXML()

Creates an xml representation (in the form of a SimpleElements) of the utilityspace.

Returns:

A representation of this utilityspace or null when there was an error.

IsComplete

public java.lang.String IsComplete()

Wouter: this function *should* check that the domainSubtreeP is a subtree of the utilSubtreeP, and that all leaf nodes are complete. However currently we only check that all the leaf nodes are complete,

Returns:

null if util space is complete, else returns string containging explanation why not.

setReservationValue

public void setReservationValue(double newRV)

Parameters:

newRV - new reservation value.

setDiscount

public void setDiscount(double newDiscount)

Parameters:

newDiscount - new discount factor.

getReservationValue

public java.lang.Double getReservationValue()

The reservation value is the least favourable point at which one will accept a negotiated agreement. Also sometimes referred to as the ‘walk away’ point. This is value remains constant during the negotiation. However, by default, the reservation value descreases with time. To obtain the discounted version of the reservation value, use getReservationValueWithDiscount(Timeline).

Returns:

undiscounted reservation value of the preference profile (may be null).

getReservationValueUndiscounted

public double getReservationValueUndiscounted()

Equivalent to getReservationValue(), but always returns a double value. When the original reservation value is null it returns the default value 0.

Returns:

undiscounted reservation value of the preference profile (never null).

See Also:

getReservationValue()

getReservationValueWithDiscount

public double getReservationValueWithDiscount(double time)

The discounted version of getReservationValue().

Parameters:

time - at which we want to know the utility of the reservation value.

Returns:

discounted reservation value.

getReservationValueWithDiscount

public double getReservationValueWithDiscount(Timeline timeline)

The discounted version of getReservationValue().

Parameters:

timeline - specifying the current time in the negotiation.

Returns:

discounted reservation value.

getFileName

public java.lang.String getFileName()

Returns:

filename of this preference profile.

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

getDiscountFactor

public final double getDiscountFactor()

Returns:

discount factor of this preference profile.